# Permission Set

Applies or updates permissions on SharePoint sites, document libraries, and folders. Accepts either an Excel file (one row per object) or a JSON file (single object).

Filename pattern:

Excel: filename must contain permissionset or permissionsset (case-insensitive).
Example: 20240115 permissionset matters.xlsx
JSON: filename must contain PermissionSet with a .json extension.
Example: PermissionSet.json

# Excel format

# Targeting

Each row must identify the site to connect to and, optionally, the specific object to apply permissions to.

Name	Required	Description
MatterCode	Conditional	Matter identifier. Required when SiteUrl and Url are not provided. Resolves the site URL from the matter list.
ClientCode	No	Client identifier used together with MatterCode to resolve the matter.
SiteUrl / WebUrl	Conditional	Direct URL of the SharePoint site. Required when MatterCode is not provided and Url does not contain a site URL.
Url	Conditional	URL of the site, library, or folder. When SiteUrl and MatterCode are both absent, the handler uses Url as the site URL.
ObjectUrl	No	Specific object (folder or document) within the resolved site to apply permissions to.
Folder	No	Folder path within the matter's document library. When the matter has exactly one document library, the folder path is combined with the doclib URL.

# Permission source

Name	Required	Description
PermissionSet	Conditional	Name of a `PermissionSetCfg` defined in config.json. Roles and members are taken from the configuration. Required when no `DomainMembers.` or `Groups.` columns are present.
DomainMembers.`<RoleName>`	No	Semicolon-separated list of domain users or groups to assign to `<RoleName>`.
Groups.`<RoleName>`	No	Semicolon-separated list of SharePoint group names to assign to `<RoleName>`.

<RoleName> must match a role in the referenced PermissionSetCfg or be a SharePoint built-in role type (opens new window) (Reader, Contributor, Full Control).

Both approaches can be combined: use PermissionSet to define the role structure and add DomainMembers.* or Groups.* columns to override members per row.

# Behavior overrides

These columns override the corresponding settings from the referenced PermissionSetCfg for that row:

Name	Required	Description
DisableInheritance	No	Boolean. Break permission inheritance on the target object.
CopyRoleAssignments	No	Boolean. When breaking inheritance, copy the parent's role assignments first.
ResetPermissions / ResetPermission	No	Boolean. Remove all existing role assignments before applying new ones.
RemoveCurrentPermissions / RemovePermissions / RemoveCurrentPermission / RemovePermission	No	Boolean. Remove all current permissions.
ReAssignPermissions / ReAssignPermission	No	Boolean. Force reapplication of permissions even if the object already has the correct assignments.

# Example

ClientCode	MatterCode	PermissionSet	DisableInheritance	CopyRoleAssignments	DomainMembers.Contribute	Groups.Read
ACME	00123	MatterSite	true	false	alice@contoso.com	Matter Readers
ACME	00124	MatterSite	true	false	bob@contoso.com; carol@contoso.com

# JSON format

A JSON file with a .json extension. Fields:

Field	Required	Description
MatterCode	Conditional	Matter identifier. Required when SiteUrl is not provided.
ClientCode	No	Client identifier used together with MatterCode.
SiteUrl	Conditional	Direct URL of the SharePoint site. Required when MatterCode is not provided.
ObjectUrl	No	Specific object within the site to apply permissions to.
Folder	No	Folder path within the matter's document library.
PermissionSet	No	Name of a `PermissionSetCfg` in config.json.
DisableInheritance	No	Boolean.
ResetPermissions	No	Boolean.
RemoveCurrentPermissions	No	Boolean.
CopyRoleAssignments	No	Boolean.
Roles	No	Array of role objects. Each has `RoleType` (or `Name`) and either `DomainMembers` or `Groups` (string arrays).

Example:

{
  "MatterCode": "32211",
  "RemoveCurrentPermissions": true,
  "Roles": [
    { "RoleType": "Editor", "DomainMembers": ["Everyone"] },
    { "RoleType": "Contributor", "Groups": ["DMS Admin"] }
  ]
}

PermissionSetCfg — defines named permission sets referenced by this handler